package contegor.scire.structure;

import java.util.List;
import java.util.concurrent.Future;

import contegor.scire.core.ScireException;
import contegor.scire.core.Task;
import contegor.scire.core.Transaction;
import contegor.scire.core.Version;

/**
 * Connection with a {@link ConceptCloud} set through their {@link DockingModule}.
 * Any implementation must ensure that any object returned is a duplicate of what the {@link ConceptCloud} produced. 
 *
 * @version $Revision: 1.1 $
 * @author  Héctor Cirbián Pousa ($Author: hector $)
 */
@Version("$Id: Connection.java,v 1.1 2010-02-01 10:56:44 hector Exp $")
public interface Connection {

  /** Sets if the {@link Connection} will commit automatically its {@link Task}s or not. */
  public void setAutocommit(boolean autocommit);

  /** Returns if this {@link Connection} commits automatically its {@link Task}s. */
  public boolean isAutocommit();

  /**
   * Submits a {@link Task} for execution and returns a {@link Future} representing the pending results of the task.
   * The {@link Future#get()} method will return the task's result upon successful completion.
   * 
   * The processing results are returned as a {@link List} of <T>, and will be always duplicates of what
   * {@link ConceptCloud}s holds.
   *
   * 
   * This is an asynchronous method. If you would like to immediately block waiting for the task execution, you can use constructions 
   * of the form <code>result = exec.submit(aCallable).get();</code>.
   *
   * @param <T> The method will return the same {@link Object} types as the {@link Task} produces.
   * @param msg {@link Task} to submit.
   * @param a {@link Future} representing pending completion of the task.
   */
  public <T> Future<List<T>> submit(Task<T> msg);

  /**
   * Commits all tasks executed in the current {@link Transaction} and starts a new one.
   * 
   * @throws Exception any that arises performing the commit. Mainly will be {@link ScireException}. 
   */
  public void commit() throws Exception;

  /**
   * Rolls back all tasks executed in the current {@link Transaction} and starts a new one.
   * 
   * @throws Exception any that arises performing the rollback. Mainly will be {@link ScireException}. 
   */
  public void rollback() throws Exception;

}